CONTENTS

1. Overview

This example demonstrates the use of the µC/USB Device™ Vendor device class for vendor specific bulk transfers between an embedded application on the ADSP-SC589 EZ-Board and a Windows host PC running a WinUSB based host application. Three use-cases are demonstrated:

1. A loopback operation where throughput can be measured, as well as reading and writing memory on the device.
2. Access of files on the host PC via the USB extension to the STDIO service.
3. Synchronous and Asynchronous, bulk transfers using the Micriµm supplied Echo demo application to echo the data sent by the host.

The first two use-cases and host application will be familiar to customers migrating from VisualDSP++® 5.0, where the host application provides loopback and File I/O over USB. This host application is separate from the Micriµm example. However, all three use-cases utilize the same Windows' driver.

2. Software configuration

2.1 µC/USB Device™ Stack Configuration

The example uses the µC/USB Device™ Stack for CrossCore® Embedded Studio (µC/USBD) with the Vendor class. The required settings are provided in the µC/USB Device tab of the system.svc dialog. These represent the baseline configuration for the example application and may require adjustment for any extension of this application.

Please note: the Project options for the example are set to avoid unhelpful warning messages. If you wish to change these settings please perform the following instructions:

• The -Wno-unused-but-set-variable and -Wno-unused-function compiler option has been added to avoid warnings. This option can be changed by removing the options in Project Properties => C/C++ Build => Settings => CrossCore ARM Bare Metal C Compiler => Additional Options

  

2.2 µC/OS-III™ Real-Time Kernel Configuration

µC/USBD requires the use of the µC/OS-III™ Real-Time Kernel for CrossCore® Embedded Studio (µC/OS-III). This example is configured to use a pre-built library file, libucos3.dlb, defined by the "USB Examples' Support component". You will be required to obtain the full µC/OS-III™ Real-Time Kernel for CrossCore® Embedded Studio in order to extend the application to meet your own requirements.

If you have µC/OS-III Product installed you can add it to your project in place of the USB Examples' Support component. Before adding the µC/OS-III component, first remove the USB Examples' Support component from the System Configuration Overview" tab:

1. Add the µC/OS-III™ Real-Time Kernel for CrossCore® Embedded Studio component release 2.6.0 to your project.
2. Ensure the following is set under C/C++ Build => Settings => CrossCore Arm C/C++ compiler => Preprocessor => Preprocessor definitions:

   ADI_USE_UCOS3_SOURCE

   µC/OS-III™ Real-Time Kernel for CrossCore® Embedded Studio 2.6.0 and above defines this variable automatically.

The µC/OS-III settings other than the defaults that are built into libucos3.dlb are:

3. Hardware Requirements and Setup

The requirements of the USB software are as follows:

• ADSP-SC589 EZ-Board and appropriate emulator ICE.
• Windows 7 or 8.1 (32 or 64 bit)
• PC with available USB port.

We recommend using a host PC with a built-in USB 2.0 controller otherwise performance will be greatly reduced. Even USB 2.0 plug-in controllers will show a decrease in performance compared to systems with built-in USB 2.0 controllers.

Please also note that using other USB devices simultaneously may slow down the performance of the example. Shutting down CCES after loading the firmware will allow the device to operate as fast as possible.

No particular switch settings are required on the EZ-Board to run the USB application.

4. Using the Arm USB 2.0 Connection

5. Using the Vendor Bulk Example

The same host application uC-USBD-VENDOR\Host\Examples\Windows\VendorBulk\Visual Studio 2010\hostapp.exe is used for both use-cases; It must be run from a Windows command line. Use the -h switch for a list of available options. In addition to headline-functions, support is provided for other simple commands such as dumping memory, filling memory, getting firmware version, etc.

Note, that setting breakpoints in the firmware may cause the host utility to timeout depending on the method used by the host to open a connection with the device. The loopback example uses asynchronous I/O and is capable of timing out while the redirect_IO example uses synchronous I/O and will not time out. If you execute an asynchronous Read() or Write() from the host and hit a breakpoint on the device before completing the transaction you will timeout. Just be sure not to place breakpoints in code that performs the read or write and you should not timeout.

5.1 General Operation

The hostapp and the Vendor bulk device application maintains the following protocol of host initiated transfers

1. Command Phase.

   A 12 byte command block is sent down with a command, the data size and an optional 4-byte value

2. Data Phase

   The data phase will either be an IN (device to host) or OUT (host to device) transfer or a combination of both.

For each command given, the hostapp will

• Transmit a command block to query support
• Receive a command block conforming support
• Transmit a command block with the details of the action
• Perform action required by command

5.2 Loopback Operation

The loopback function involves data being send from the host to the device and back again. The host verifies that the data is correct and performs some throughput calculations which it displays to the user. The loopback program flow is as follows:

Running hostapp -l will display a screen - that is continuously updated - such as the following:

The header information should be self-explanatory, but note that the "Transfer size" will either be constant with -l or -c options and variable with -r option.

The bottom table gives the throughput figures (in Mbytes per second, 1MB = 1024*1024 bytes) in both directions and is detailed as follows:

5.3 File I/O and STDIO Operation

The File I/O function allows the device to open files on the host, read and write these files, and redirects stdio from the device to the host window for viewing by the user. The redirect_IO example can be used to allow users to get debug (printf) information from the device faster and even without CCES running. The File I/O program flow is as follows:

         HOST SIDE                                    DEVICE SIDE
-----------------------------------------------------------------------------------------
T0)                                                 - waits for a command
T1) - establishes communication with device
T2) - sends down command (-u, etc.)
T3) - wait for I/O requests                         - receives command and starts I/O
T4)                                                 - sends I/O request
T5) - receives I/O request and handles it           - waits for reply
T6) - sends reply
T7) - waits for next I/O request                    - receives reply

This example demonstrates File operations as well as STDIO operations between SC589 EZ-Board and a Windows host PC.
All messages from device will be shown with < DEVICE > header in the GREEN color. Similarly all messages from host will be shown with < HOST > header in CYAN color.
All errors will be printed in RED color with respective < DEVICE > and < HOST > headers.
Follow below instructions to run the demo-

• Open command prompt, navigate to uC-USBD-VENDOR\Host\Examples\Windows\VendorBulk\Visual Studio 2010 and type .\hostapp.exe -u command.
• As soon as you run hostapp -u, following message will be seen-

                                                              

 < HOST > Start servicing USBIO
 

 < DEVICE > This is not an error, but errors will print in red

 
 < DEVICE >                                                   
 < DEVICE > What is your name (please don't use spaces)?      
 

abcd
 < DEVICE > Ok abcd, how many test lines should I print? (please enter using only characters 0-9 with no spaces)           

2


 < DEVICE > Test line   1                                     
 < DEVICE > Test line   2                                     
 < DEVICE >                                                   
 < DEVICE > fopen                                             
 < DEVICE > Read 0x5a8 bytes from .\data\test.txt             
 < DEVICE > Wrote 0x5a8 bytes to .\data\txt2.txt              
 < DEVICE >                                                   
 < DEVICE > Read 0x325e0 bytes from .\data\bulee.jpg          
 < DEVICE > Wrote 0x325e0 bytes to .\data\jpg2.jpg            
 < DEVICE >                                                   
 < DEVICE > To view the image go to location                                               
 < DEVICE > ".\data"                                          
 < DEVICE > with respect to hostapp application and open jpg2.jpg file


 < HOST > Device terminated USBIO successfully                

5.3.1 Details of USBIO redirection usage

This section explains the example files used for USBIO redirection.

VendorDemo.c:

It contains main() function which calls following functions:

• BSP_Init() - Initialize board specific settings
• OsInit(&err) - Initialize the RTOS
• adi_initComponents() - Initialize managed drivers and/or services including USB
• App_TaskCreate() - Creates USBIO_TaskStart
• OSStart(&err) - Starts the RTOS

app_usbio.c:

It defines a USBIO task module "USBIO_TaskStart" which is created by VendorDemo.c:App_TaskCreate()

• This task pends on a semaphore by calling app_bulktest.c:USBIO_WaitForHost()
• It calls following APIs (defined in libucusbd.dlb) to intialize the stdio service and redirection of STDIN, STDOUT, STDERR and file operations to USB.
  • adi_stdio_USBD_InitUsb() - Initializing the STDIO service and USB device as STDIO
  • adi_stdio_USBD_RedirectUsb() - Redirecting all streams to USB
• After these calls IO operations can be performed over USB.
• Following APIs need to be called after USBIO operation is completed-
  • adi_stdio_USBD_StopUsb() - Inform host that we are done with USBIO
  • adi_stdio_USBD_CloseUsb(): Closing USB as STDIO service and terminating STDIO service
• Returns back control to app_bulktest.c:App_USBD_BulkTestApp for receiving more commands from host by calling app_bulktest.c:USBIO_ReturnControl().

app_bulktest.c:

Defines App_USBD_BulkTestApp" task

• It is created inside prebuilt libucusbd.dlb library and waits for command block from host.
• After receiving the command block it responds according to the request of host.
• In demo example, once "hostapp -u" command is received, App_USBD_BulkTestApp task posts the semaphore and wait for signal from app_usbio.c:USBIO_TaskStart task after USBIO operation are done.

usb_redirect_io.c:

Defines PerformIO function for demonstrating the IO operations.

5.4 Note

The host application provided in uC-USBD-VENDOR\Host\Examples\Windows\VendorBulk\Visual Studio 2010\hostapp.exe does not not build right away. It requires setupapi.lib and winusb.lib libraries and related header files provided by Microsoft to build.